SQL Server 2008: SQL Server Web Services - Building Web Services (part 2)

The AS HTTP Keyword Group

The AS HTTP statements describe the protocol, ports, virtual path, and TCP/IP bindings for the endpoint. This keyword group is of interest to security professionals because this is where you can implement IP restrictions, authentication, and other lockdown mechanisms.

In the example shown in Listing 48.3, HTTP is the transport protocol. But you could just as easily use TCP if your application demands it: when creating a TCP endpoint, you specify AS TCP instead of AS HTTP. Then you add the following parameters:

• LISTENER_PORT— Specifies an integer-valued port number on which the server listens for incoming requests. The default is 4022.

• LISTENER_IP— Specifies an incoming IP address on which the TCP listener accepts connections. The default is the keyword ALL (that is, listening on all IP addresses).

Next, you specify that the AUTHENTICATION method is INTEGRATED. Microsoft recommends INTEGRATED (which includes both KERBEROS and NTLM) and KERBEROS as the most secure ways of authenticating to endpoints, although they are not necessarily platform-independent ways. This approach is in contrast to using BASIC or DIGEST authentication. In case the endpoint consumer requires BASIC authentication, SQL Server requires that the HTTP port of the web service be secured via Secure Sockets Layer (SSL).

DIGEST authentication is also available, but only a domain-level account may be used in the AUTHORIZATION section for the endpoint to be successfully created.

Using DIGEST allows for the additional keyword AUTH_REALM, whose string value represents the challenge hint required by this type of authentication.

Next, you specify the PATH (/opensql) to the web service. PATH is simply the part of the URL that follows the server and domain name portion of a URL (for example, http://ServerDomainName/PATH). Paths are sometimes also referred to as virtual names. Clients connecting to the HTTP endpoint thus access it via the URL http://ServerDomainName/opensql.

This method of specifying the PATH is similar to the way virtual directories are used with IIS, and the reason is that IIS and SQL Server register their endpoints similarly with the HTTP API. When the web service is called by a client, the HTTP API responds by farming the request out to SQL Server.

The URL specified by endpoint 'ENDPOINTNAME' is already registered
to receive requests or is reserved for use by another service.

Next in the syntax, you specify the PORTS on which SQL Server listens for requests for this endpoint. The example in Listing 48.3 specifies both CLEAR (the unsecured standard HTTP port, which defaults to 80) as well as SSL (the standard SSL port, which defaults to 443). You can also specify nondefault numeric values for CLEAR_PORT and SSL_PORT, but this example simply restates the default for clarity.

Note that it is essential you do not use port numbers owned by other network services (such as email, telnet, and so on), although SQL Server may allow you to do so. Only one port can be specified each for CLEAR_PORT and SSL_PORT.

In addition to specifying ports, you can restrict or grant endpoint access to specific IP addresses by using a combination of the keywords RESTRICT_IP and EXCEPT_IP. RESTRICT_IP defaults to NONE (that is, no IP addresses are restricted), but you can change this to ALL to prevent users from accessing the endpoint (which is useful during offline maintenance periods). For EXCEPT_IP, you can add specific client IP addresses in parentheses. Here’s an example:

CREATE ENDPOINT EPT_SQL2008UnleashedIPExample
AUTHORIZATION [MyDomain\SQLWebServicesClient]
STATE = STARTED
AS HTTP
(
    AUTHENTICATION = (INTEGRATED),
    PATH = '/opensql2/',
    PORTS = (CLEAR, SSL),
    CLEAR_PORT = 80,
    SSL_PORT = 443,
    SITE = '*',
    COMPRESSION = ENABLED,
    RESTRICT_IP = ALL,
    EXCEPT_ID = 192.168.10.1
)
FOR SOAP
(
    WEBMETHOD 'urn:www-samspublishing-com:examples'.'WM_GetEmployeeBasics2'
    (
        NAME = 'AdventureWorks2008.dbo.GetEmployeeBasics',
        SCHEMA = STANDARD,
        FORMAT = ALL_RESULTS
    ),
    WSDL = DEFAULT,
    BATCHES = DISABLED,
    SCHEMA = STANDARD,
    LOGIN_TYPE = WINDOWS,
    SESSION_TIMEOUT = 120,
    DATABASE = 'AdventureWorks2008',
    NAMESPACE = 'urn:www-samspublishing-com:examples',
    CHARACTER_SET = XML
);


					  

Next, you use the SITE keyword to specify the hostname(s) used on the server hosting the endpoint. In this case, ’*’ restates the default (that is, all hostnames reserved by the local machine), but you can use a specific host name (such as ’hostname’) or all hostnames (that is, '+'). This capability is useful (and necessary) when multiple host headers are in play for the same IP address.

The NAMESPACE keyword indicates to clients that the web method originates from a specific organizational entity. This prevents confusion when comparing the XML generated by this web service with that of any other organization that might expose a web method of the same name on an endpoint of the same name (which is an entirely possible situation).

COMPRESSION is an interesting optional keyword because, when specified, it tells SQL Server to decompress its incoming SOAP requests if they have been compressed using gzip; then, in turn, it tells SQL Server to use gzip on the outgoing responses. You might think that web services over SOAP are too slow for the average application because of the sheer byte count of SOAP XML documents. However, using gzip on an XML file usually results in a compression ratio of greater than 80%.

When COMPRESSION is set to ENABLED, both the client and server must support gzip compression for web service compression to work properly, although the web service can still process uncompressed requests with uncompressed responses even with the setting turned on.

To enable compression on IIS 6 (on Windows 2003 Server, Standard Edition), you follow these steps:

The Web Sites Properties dialog box should look something like the one in Figure 1 when these steps are complete.